Formatting Content With Markdown#
To effectively convey messages, a good design is essential. Even if your content is amazing, if it is presented as just a wall of plain text, chances are that people will not pay a lot of attention to it. Luckily, Jupyter Book has plenty of different options to format text, including media and much more.
In this section, we’ll cover key Markdown formatting basics along with some MyST formatting features. MyST is a markup language inspired by RMarkdown, supported by both .ipynb and .md files in Jupyter Book. It offers advanced formatting options and lets you integrate interactive elements, such as widgets, dropdowns, and code snippets, into your content. For more details, we encourage you to explore the MyST website.
Now, let’s start with the fundamentals.
Headings#
You can add headings using Markdown’s syntax by adding # before your heading. You can vary the heading level by increasing the amount of hash signs:
# Heading 1
## Heading 1.1
### Heading 1.1.1
Italic#
To make a text italic add _ or * before and after the word:
Syntax |
Output |
|---|---|
|
italic |
|
italic |
Bold#
To make a text bold add __ or ** before and after the word:
Syntax |
Output |
|---|---|
|
bold |
|
bold |
(Nested) Lists#
You can build nested itemized or enumerated lists using either * or - before a word:
* One
- Sublist
- This
- Sublist
- That
- The other thing
Which results in:
One
Sublist
This
Sublist
That
The other thing
You also create numbered lists by using 1. etc. before your point:
1. Here we go
1. Sublist
2. Sublist
2. There we go
3. Now this
Which results in:
Here we go
Sublist
Sublist
There we go
Now this
Horizontal Lines#
You can add horizontal rules using three underscores ___ resulting in:
Blockquotes#
To create a blockquote, it is as simple as putting a > before a text.
Here is a blockquote:
> Beautiful is better than ugly.
> Explicit is better than implicit.
> Simple is better than complex.
> Complex is better than complicated.
And it’s formatted like this:
Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated.
Embedded Code#
You can embed code meant for illustration instead of execution in Python by adding `` around statements:
`def f(x):`
` return x**2`
Which results in:
def f(x):
return x**2
Since you need to add this line by line, this might ruin your code formatting. Instead, consider using the HTML formatting, adding <code> before and </code> after your code:
<code>def f(x): return x**2</code>
Which results in:
def f(x): return x**2
Writing Latex#
Let’s use $$ to render a block of latex:
Syntax |
Output |
|---|---|
|
$\(F(k) = \int_{-\infty}^{\infty} f(x) e^{2\pi i k} \mathrm{d} x\)$ |
Plotting in the Notebook#
Notebooks support a variety of fantastic plotting options, including static and interactive graphics. This magic configures matplotlib to render its figures inline:
%matplotlib inline
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 2*np.pi, 300)
y = np.sin(x**2)
plt.plot(x, y)
plt.title("A little chirp")
fig = plt.gcf() # let's keep the figure object around for later...
import plotly.figure_factory as ff
# Add histogram data
x1 = np.random.randn(200) - 2
x2 = np.random.randn(200)
x3 = np.random.randn(200) + 2
x4 = np.random.randn(200) + 4
# Group data together
hist_data = [x1, x2, x3, x4]
group_labels = ['Group 1', 'Group 2', 'Group 3', 'Group 4']
# Create distplot with custom bin_size
fig = ff.create_distplot(hist_data, group_labels, bin_size=.2)
fig.show()
Special Content Blocks - Directives and Roles#
Directives and Roles are somewhat similiar to functions for markup language and allow for specific customizations of the look and feel of your book. Both accept various kinds of inputs, which are explained in further detail below.
Directives#
With directives, you can adjust the look and feel of your Jupyter Book.
Directives are written like this:
```{mydirectivename}
My directive content
Where `{mydirectivename}`would be the name of the directive. However, this directive does not yet exist. While you can integrate directives, there are many directives already implemented in Jupyter Book.
For instance, if you want to add a note, you can use:
Note
Here is a note
Which results in:
```{note}
Here is a note
Roles#
Roles are very similar in usage. However, they are somewhat simpler and are limited to one line.
For example:
Some content {rolename}`and here is my role's content!`
Where {rolename} would be the name of the role.
For instance, if you want to reference another page of your book, you can use the {doc}role:
{doc}`../1_github/intro`
Which results in:
What Roles and Directives Are Available?#
For more information on what roles and directives you can use, check out:
For building custom Special content blocks
Include Links#
When adding links, you have several options. Here are the most common methods:
External Links#
To link to an external website, use the following format: [text](https://example.com)
Example |
|
Result |
URL in New Tab#
If you want the link to be opened in a new tab automatically, your can use the following HTML based format: <a href="https://example.com" target="_blank">text</a>
Example |
|
Result |
Linking Another Page In Your Course#
If you want to reference another file within your own project, use a relative path: [text](relative_path)
Note
When using relative paths, ../ is a special notation that tells the system to move up one level in the folder structure.
Example |
|
Result |
Check the previous chapter |
This method gives you full flexibility in how you phrase the link text. Alternatively, you can use the {doc} role, as explained above.
Direct URL#
You can also display a URL as a clickable link without custom text by using angle brackets < >: <URL>
Example |
|
Result |
How about a quick exercise?
Next Section:#
In the next section, you will learn how to embed images, videos, and slides.